| TWiki . EBR . ReportTool |
The ReportTool produces statistical information the orders, users and accounts.
It is a standalone utility that is run from the command-line. It produces output in DocBook XML format which can be transformed into several different presentation formats, including HTML, RTF and PDF.
For creating the DocBook XML files the following components are required:
- the ReportTool.zip file
- a CUI/CAI database installed (with the changes required by CaiMilestoneFour applied)
- access to an EBR DataLayer
- Java J2SE 1.4 .0 or above
The choice of DocBook tools you use to transform the DocBook XML file(s) created by the ReportTool is left to you.
These instructions only cover installation on a UNIX type system. For Windows and others platforms the exact steps may vary slightly.
The ReportTool is distributed as a Zip available to download from the SNAS, extract the file into a folder of your choice.
You should see something similar to the following:
[martin@ws1 repdocs]$ ls -ltr total 16 drwxrwxr-x 10 martin martin 340 Mar 2 16:58 lib drwxrwxr-x 4 martin martin 136 Mar 3 11:15 templates -rw-r--r-- 1 martin martin 400 Mar 23 17:15 etc drwxrwxr-x 3 martin martin 102 Mar 23 17:30 build drwxr-xr-x 4 martin martin 136 Mar 23 17:31 logs
There are two configuration files for the ReportTool, "velocity.properties" and "reptools.props".
These can be found in etc/samples/config and should be moved to the root of the install directory.
"velocity.properties" is required for the internal template mechanism used by the ReportTool. Have a look inside if you are having problems with logging or finding the templates, you may need to change the paths to suit your local system needs.
The "reptools.props" file configures some report settings (operator name, country, etc.) and how to connect up the ReportTool with the components it requires. See the file for more details (you MUST set datasource and datalayerroot), each parameter name should be self-explanatory, except for "datasource". For details on this parameter see below.
Before attempting to launch the ReportTool, the CLASSPATH environment variable must be set correctly.
It must include ALL the files listed in the "lib" folder, the "build" folder and the current working folder ("."). For example, in the example "go" quick-start shell script provided in the ReportTool distribution this is achieved by the following commands:
export CLASSPATH=.:build/classes
for i in $REPTOOL/lib/*.jar
do
export CLASSPATH=$CLASSPATH:$i
done
Before using the ReportTool you will have to write a small Java class to configure the ReportTool to use the database system you have chosen for the CUI/CAI. The class must implement the simple "com.orctel.ebr.network.DataSourceFactory" interface, i.e. return a DataSource object.
An example class using a MySQL database on the localhost is shown below:
package my.datasource;
import org.gjt.mm.mysql.jdbc2.optional.*;
import javax.sql.DataSource;
public class MyFactory implements com.orctel.ebr.network.DataSourceFactory
{
public DataSource getDataSource()
{
MysqlDataSource ds = new MysqlDataSource();
ds.setUser("my_ebr_user");
ds.setPassword("my_ebr_password");
ds.setDatabaseName("ebrusr");
ds.setServerName("localhost");
ds.setPort(3306);
return ds;
}
}
That is it. Obviously, if you are using a different database the import
org.gjt... statement should be replaced with whatever driver is needed for your
system. Also, your database DataSource may
require additional / different parameters to be set, but the overall goal is the
same, to return a correctly configured data source.
Create the above file in the folder you installed the ReportTool and compile it there.
e.g.
$ javac -d build/classes MyFactory.javaYou should now see a MyFactory?.class in the build/classes folder:
[martin@ws1 repdocs]$ ls -lrt build/classes/my/datasource/ total 4 -rw-r--r-- 1 martin martin 656 Mar 23 17:55 MyFactory.classNow edit "reptool.props" and ensure that the datasource parameter is set to use your new class, e.g.
datasource=my.datasource.MyFactory
You are now ready to start using the ReportTool.
It is recommended that you create a "docbook" folder in the installation directory as a target for the output files.
To generate a "summary report" of the accounts in the database, the ReportTool can invoked with a command similar to:
$ java com.orctel.ebr.reports.SummaryReport docbook/summary.vm 01-Feb-2004 28-Feb-2004 > docbook/book.xmlThe arguments in order are:
docbook/summary.vm - the name of the master template to use.
01-Feb-2004 - start date of report
28-Feb-2004 - end date of report
In this example the output is redirected to docbook/book.xml,
creating a valid DocBook XML format
file.
To generate a "detailed report" of the accounts in the database, the ReportTool can invoked with a command similar to:
$ java com.orctel.ebr.reports.DetailedReport docbook/detailed.vm 01-Feb-2004 28-Feb-2004 > docbook/book.xmlThe arguments are the same as for the Summary Report.
This is system dependent. It is left to the operator to select the
appropriate tools for their environment. An Internet search for "docbook
tools" will bring up a wealth of options.
You are free (and encouraged) to suit the templates (inside the
templates folder) for your own local needs. The default output is
very plain and simple as it is obvious that operators will want to heavily
customise the reports for their own purposes (e.g. translation, maybe adding a
company logo, etc.).
The "plain" (non-DocBook) templates that were used during development are also supplied in the distribution. These are provided "as is" and are merely intended to help partners test use of the templates / any changes they make. They could even be used as the basis of a non-Trash.DocBook report if partners want to avoid such an approach.
Actication of the "plain" reports can be achieved by the following:
$ java com.orctel.ebr.reports.DetailedReport plain/detailed.vm 01-Feb-2004 28-Feb-2004This will produce a detailed report to the screen in a simple ASCII format.
----- Revision r1.4 - 08 Sep 2004 - 10:16 GMT
- MarkEarlam
|